02.3 execution

Execution

Execution is the process an agent follows to transform a user request into a final response.

Rather than sending a prompt directly to the language model, BindAI executes a structured pipeline that prepares context, retrieves knowledge, executes tools when necessary, and produces the final result.

---

Execution Pipeline

A typical execution follows this sequence.

User Input
      │
      ▼
Initialization
      │
      ▼
Knowledge Retrieval
      │
      ▼
Memory Injection
      │
      ▼
Model Generation
      │
      ▼
Tool Execution (optional)
      │
      ▼
Model Generation
      │
      ▼
Finish

Each stage has a single responsibility.

---

Initialization

The execution begins by creating an execution state.

This stage:

• initializes the execution context
• stores the user input
• prepares the conversation
• builds the initial model request

If the conversation is empty, the system prompt is automatically inserted.

---

Knowledge Retrieval

If the agent has an attached knowledge source, BindAI retrieves relevant information before contacting the language model.

The retrieved context is appended to the request so the model can answer using external information.

If no knowledge source exists, this step is skipped.

---

Memory

If the agent uses memory, previous conversation history is injected into the request.

Memory allows the model to maintain context across multiple interactions.

Without memory, every execution is independent.

---

Model Generation

After the request is prepared, the provider generates a response.

For example:

response = provider.generate(request)

The provider returns:

• generated text
• tool calls (if any)
• token usage
• structured output (when requested)

---

Tool Execution

If the language model requests a tool, BindAI executes it automatically.

Example flow:

Model

↓

Search Tool

↓

Search Result

↓

Model

Tool outputs are inserted into the conversation as tool messages before another model generation occurs.

This loop continues until the model returns a final answer without requesting additional tools.

---

Tool Iterations

Agents can call multiple tools during a single execution.

Model

↓

Tool A

↓

Model

↓

Tool B

↓

Model

↓

Final Response

To prevent infinite loops, BindAI enforces a configurable maximum number of tool iterations.

---

Finish

When the model no longer requests tools, execution completes.

The final response is converted into an AgentResult.

Example:

result = agent.chat(
    "Explain BindAI."
)

print(result.output)

---

AgentResult

Every execution returns an AgentResult.

AgentResult(
    success=True,
    output="...",
    error=None,
)

Fields include:

Field	Description
success	Indicates whether execution completed successfully
output	Final response returned by the agent
error	Error message if execution failed

---

Structured Output

If an output model is provided, BindAI attempts to parse the response into that object.

result = agent.chat(
    "Generate a user profile.",
    output=UserProfile,
)

When parsing succeeds:

result.output

contains an instance of UserProfile instead of raw text.

---

Execution Context

Every execution receives an ExecutionContext.

The context stores runtime information such as:

• variables
• execution state
• events
• metadata

Tools and workflows also receive an execution context.

---

Middleware

Middleware can execute code before and after agent execution.

Example:

Before Execute

↓

Agent Pipeline

↓

After Execute

Middleware is commonly used for:

• authentication
• logging
• metrics
• request validation
• response transformation

---

Events

During execution, BindAI publishes lifecycle events.

Typical events include:

AgentStartedEvent

↓

ModelRequestEvent

↓

ModelResponseEvent

↓

ToolExecutedEvent

↓

AgentFinishedEvent

Applications can subscribe to these events for monitoring and analytics.

---

Hooks

Hooks provide another extension point.

Unlike events, hooks are attached directly to an agent and execute as part of its lifecycle.

They are useful for application-specific behavior after an execution completes.

---

Streaming

Agents can stream tokens instead of waiting for the full response.

for chunk in agent.stream(
    "Write a poem."
):
    print(chunk.delta, end="")

Streaming begins immediately after model generation starts.

---

Error Handling

If an exception occurs during execution, BindAI returns:

AgentResult(
    success=False,
    output=None,
    error="..."
)

Applications can inspect the result instead of catching provider-specific exceptions.

---

Execution Flow Example

A complete execution may look like this.

User

↓

Initialization

↓

Memory

↓

Knowledge

↓

Model

↓

Tool

↓

Model

↓

Finish

↓

AgentResult

Most executions complete after a single model call, while more advanced agents may iterate through several tool calls before returning the final answer.

---

Best Practices

• Keep prompts focused.
• Use tools only when necessary.
• Limit tool iterations.
• Use structured output for machine-readable responses.
• Enable streaming for long responses.
• Attach middleware for cross-cutting concerns.
• Use events for monitoring instead of modifying the execution pipeline.